Skip to content

docs: Fix Python connector tutorial environment setup documentation #72534

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
devin-ai-integration wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: Fix Python connector tutorial environment setup documentation #72534

devin-ai-integration wants to merge 3 commits into from
+265 −32

Conversation

@devin-ai-integration
Copy link
Contributor

@devin-ai-integration devin-ai-integration bot commented Feb 2, 2026 •
edited
Loading

What

Fixes the environment setup documentation for the custom Python connector tutorial, which had numerous issues making it impossible to follow successfully.

Issues fixed:

  • Removed duplicate git clone instructions (appeared twice in the original)
  • Fixed inconsistent connector naming (was source-exchange-rates-tutorial in some places, source-survey-monkey-demo in others)
  • Added missing critical setup steps (source module creation, pyproject.toml configuration, entry points)
  • Replaced vague instructions with complete, working code examples
  • Fixed references to files that didn't exist (secrets/config.json, configured_catalog.json)
  • Updated verification steps to show successful output instead of expected failures

Requested by @ian-at-airbyte

How

Complete rewrite of the documentation to provide step-by-step instructions that:

  1. Add a prerequisites section listing required tools
  2. Provide complete pyproject.toml with proper entry point configuration
  3. Include all necessary Python files (__init__.py, source.py, run.py, main.py)
  4. Add spec.yaml with proper connector specification format
  5. Include test configuration files (secrets/config.json, configured_catalog.json)
  6. Add verification steps using spec and check commands
  7. Include final project structure overview

Updates since last revision

  • Added title="filename.extension" attributes to all code blocks for improved clarity
  • Clarified that the secrets/ directory exclusion is from the Airbyte repository's .gitignore (per reviewer feedback)

Review guide

  1. docs/platform/connector-development/tutorials/custom-python-connector/1-environment-setup.md - Single file change, complete rewrite

Key areas to verify:

  • pyproject.toml configuration follows current Poetry/CDK best practices
  • Python code examples are syntactically correct
  • spec.yaml format is valid for the Airbyte CDK
  • Tutorial flows logically into the next page (2-reading-a-page.md)
  • Code block titles match the file paths mentioned in the text

User Impact

Users following the Python connector tutorial will now be able to complete the environment setup successfully and have a working connector skeleton ready for the next tutorial section.

Can this PR be safely reverted and rolled back?

  • YES 💚

Link to Devin run: https://app.devin.ai/sessions/afe4af8e6513476b942a627e7e3d9f9e

@devin-ai-integration @ian-at-airbyte
docs: Fix Python connector tutorial environment setup documentation
b0917f9 
- Remove duplicate git clone instructions
- Add proper prerequisites section with required tools
- Provide complete pyproject.toml configuration with entry points
- Add step-by-step instructions for creating source module files
- Include proper __init__.py, source.py, run.py, main.py, and spec.yaml
- Add test configuration files (secrets/config.json, configured_catalog.json)
- Update verification steps to use spec and check commands
- Add project structure overview
- Ensure consistent connector naming (source-survey-monkey-demo)
- Fix Vale spelling error (gitignored -> excluded from Git)

Co-Authored-By: [email protected] <[email protected]>
@devin-ai-integration
Copy link
Contributor Author

devin-ai-integration bot commented Feb 2, 2026

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

ian-at-airbyte
ian-at-airbyte reviewed Feb 2, 2026
View reviewed changes
docs/platform/connector-development/tutorials/custom-python-connector/1-environment-setup.md Outdated
```

:::caution
The `secrets/` directory is excluded from Git by default. Never commit your API credentials to version control.
Copy link
Contributor

@ian-at-airbyte ian-at-airbyte Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this true about Git?

Copy link
Contributor Author

@devin-ai-integration devin-ai-integration bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is accurate. The root .gitignore file contains:

# Secrets
secrets
!airbyte-integrations/connector-templates/**/secrets

This excludes all secrets/ directories from Git tracking (except for connector templates which need placeholder secrets for scaffolding).

Copy link
Contributor

@ian-at-airbyte ian-at-airbyte Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh. This is based on the airbyte project's gitignore?

Copy link
Contributor Author

@devin-ai-integration devin-ai-integration bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is based on the Airbyte monorepo's root .gitignore. Since this tutorial is specifically about developing connectors within the Airbyte repository, the secrets/ directory will be automatically excluded.

Should I clarify this in the documentation to make it more explicit that this applies when working within the Airbyte repository?

Copy link
Contributor

@ian-at-airbyte ian-at-airbyte Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably. It confused me for a moment.

Copy link
Contributor Author

@devin-ai-integration devin-ai-integration bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated the documentation to clarify this. The text now reads: "The Airbyte repository's .gitignore excludes the secrets/ directory by default."

@ian-at-airbyte ian-at-airbyte self-requested a review February 2, 2026 20:08
@ian-at-airbyte ian-at-airbyte marked this pull request as ready for review February 2, 2026 21:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ian-at-airbyte ian-at-airbyte Awaiting requested review from ian-at-airbyte

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ian-at-airbyte